.\" Copyright (c) Rong Tao (rtoax@foxmail.com)
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.TH ultask 8  "2022-10-01" "USER COMMANDS"
.SH NAME
ultask \- User-mode process viewer and editor.

.SH SYNOPSIS
.B ultask
-p \fIPID\fR [\fI\,OPTION\/\fR]...

.SH DESCRIPTION
.\" Add any additional description here
.PP
ultask is a process modifier that can modify the memory of a running program, and can also view the process memory and VMA.
ultask is a basic command of ULPatch.

If no command line arguments are specified, some task information will be printed by default, but if command line arguments are specified, it will not be printed.

This program is also a basic command of ULPatch.

.SH REQUIREMENTS
elfutils-libelf, bfd, capstone

.SH ARGUMENTS
.SS
\fB\-p\fR, \fB\-\-pid\fR [PID]
Specify a target process's PID.

.SS
\fB\-\-dump\fR=[\fI\,TYPE\/\fR,addr=\fI\,ADDR\/\fR,size=\fI\,SIZE\/\fR]
Dump something to file, \fBaddr\fR followed by the \fIADDR\fR format string. \fBsize\fR followed by the \fISIZE\fR format string.
See also
.IR /proc/ PID /maps .
.sp
The \-\-dump option has 4 sub options:
.TP
.B \-\-dump addr=ADDR,size=SIZE
If not specify \fITYPE\fR, dump process's address memory to file.
.TP
.B \-\-dump vma,addr=ADDR
If \fITYPE\fR=\fBvma\fR, dump process's VMA to file.
.TP
.B \-\-dump vdso
If \fITYPE\fR=\fBvdso\fR, dump process's vdso VMA to file.
.TP
.B \-\-dump disasm,addr=ADDR,size=SIZE
If \fITYPE\fR=\fBdisasm\fR, disassemble a piece of code of target process.
Only compile ulpatch with \fBCONFIG_CAPSTONE\fR could use disassemble dump.

.SS
\fB\-\-jmp\fR=[from=\fI\,ADDR\/\fR,to=\fI\,ADDR\/\fR]
Specify a jump entry SRC and DST address. Followed by the \fBADDR\fR format string.
You better know what you're doing.
This action cannot be undone.

.SS
\fB\-\-map\fR [file=\fI\,FILE\/\fR,ro,noexec,addr=\fIADDR\fR]
Map a file into target process. The \fI\,FILE\/\fR should under target process \fBcwd\fR,
see
.IR /proc/ PID /cwd .
you'd better \fB--map file=$PWD/FILE\fR.

If you want to map a read-only file, set the \fBro\fR option, default rw.

If you want to remove PROT_EXEC, set the \fBnoexec\fR option, PROT_EXEC is set by default.

If you want to map to special address, set the \fBaddr\fR option, 0 by default.

.SS
\fB\-\-unmap\fR[=\fI\,ADDR\/\fR]
Unmap a vma from target process. Followed by the \fBADDR\fR format string.

.SS
\fB\-\-mprotect\fR [addr=\fI\,ADDR\/\fR,len=\fISIZE\fR,read,write,exec,none]
Set protection on a region of target task's memory. \fBaddr\fR must be aligned to a page boundary. \fBnone\fR if default, \fBread\fR,\fBwrite\fR,\fBexec\fR could combine, and conflict with \fBnone\fR.
see also
.BR mprotect (2).

.SS
\fB\-\-vmas\fR
Dump process's VMA, see also
.IR /proc/ PID /maps .

.SS
\fB\-\-threads\fR
Dump process's Thread, see also
.IR /proc/ PID /task/ .

.SS
\fB\-\-fds\fR
Dump process's File Descriptors, see also
.IR /proc/ PID /fd/ .

.SS
\fB\-\-auxv\fR
Print process's auxv, see also
.IR /proc/ PID /auxv .

.SS
\fB\-\-status\fR
Print process's status, see also
.IR /proc/ PID /status .

.SS
\fB\-\-syms\fR, \fB\-\-symbols\fR
List all symbols of target process.

.SS
\fB\-o\fR, \fB\-\-output\fR
Specify output. The output content varies according to different input parameters.

.SH COMMON ARGUMENTS
.SS
\fB\-\-log-level\fR[=\fI\,LEVEL\/\fR], \fB\-\-lv\fR[=\fI\,LEVEL\/\fR]
Specify a log level. The LEVEL could be number(see
.BR syslog (3)
) or string(debug,dbg,info,inf,notice,note,warning,warn,error,err,crit,alert,emerg).
For example, if you want to set log level to LOG_ERR, just:
.BR --lv=error .

.SS
\fB\-\-log-debug\fR
Set log level to DEBUG.

.SS
\fB\-\-log-error\fR
Set log level to ERROR.

.SS
\fB\-u\fR, \fB\-\-dry-run\fR
Don't actually run.

.SS
\fB\-v\fR[vvv...], \fB\-\-verbose\fR
Show verbose information.
You can set more \fBv\fR values to increase the verbose level and display more details.
For example, \fB-vvvvv\fR will set the verbose value to \fB4\fR, because there are 4 \fBv\fR's.

.SS
\fB\-h\fR, \fB\-\-help\fR
Show help information.

.SS
\fB\-V\fR, \fB\-\-version\fR
Show version information.

.SS
\fB\-F\fR, \fB\-\-force\fR
Force do something. For example, overwrite exist output file.

.SS
\fB\-\-info\fR
Print detailed information about features supported by the kernel and the ULPatch build. It is necessary to display this information when you are submitting a MR/PR.

.SH FORMAT
.SS
\fBADDR\fR
Address string may include a \fB0x\fR prefix or not.
.SS
\fBSIZE\fR
Size string may include a \fB0x\fR prefix or not, and size string may include a \fBKB\fR, \fBMB\fR, \fBGB\fR suffix or not.
.SH OS
Linux

.SH STABILITY
Unstable - in development.

.SH AUTHOR
Written by Rong Tao

.SH SEE ALSO
.BR ulpatch (8),
.BR ulpinfo (8),
.BR ulftrace (8),
.BR ulpconfig (8)
